home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet internetowy / Anonimowosc i bezpieczenstwo / TOR 0.1.1.24 / vidalia-bundle-0.1.1.24-0.0.7.exe / Tor / Documents / dir-spec.txt < prev    next >
Text File  |  2006-09-24  |  28KB  |  600 lines
  1. $Id: dir-spec.txt 8479 2006-09-24 17:20:41Z nickm $
  2.  
  3.                   Tor directory protocol for 0.1.1.x series
  4.  
  5. 0. Scope and preliminaries
  6.  
  7.    This document should eventually be merged to replace and supplement the
  8.    existing notes on directories in tor-spec.txt.
  9.  
  10.    This is not a finalized version; what we actually wind up implementing
  11.    may be different from the system described here.
  12.  
  13. 0.1. Goals
  14.  
  15.    There are several problems with the way Tor handles directory information
  16.    in version 0.1.0.x and earlier.  Here are the problems we try to fix with
  17.    this new design, already partially implemented in 0.1.1.x:
  18.       1. Directories are very large and use up a lot of bandwidth: clients
  19.          download descriptors for all router several times an hour.
  20.       2. Every directory authority is a trust bottleneck: if a single
  21.          directory authority lies, it can make clients believe for a time an
  22.          arbitrarily distorted view of the Tor network.
  23.       3. Our current "verified server" system is kind of nonsensical.
  24.       4. Getting more directory authorities adds more points of failure and
  25.          worsens possible partitioning attacks.
  26.  
  27.    There are two problems that remain unaddressed by this design.
  28.       5. Requiring every client to know about every router won't scale.
  29.       6. Requiring every directory cache to know every router won't scale.
  30.  
  31.    We attempt to fix 1-4 here, and to build a solution that will work when we
  32.    figure out an answer for 5.  We haven't thought at all about what to do
  33.    about 6.
  34.  
  35. 1. Outline
  36.  
  37.    There is a small set (say, around 10) of semi-trusted directory
  38.    authorities.  A default list of authorities is shipped with the Tor
  39.    software. Users can change this list, but are encouraged not to do so, in
  40.    order to avoid partitioning attacks.
  41.  
  42.    Routers periodically upload signed "descriptors" to the directory
  43.    authorities describing their keys, capabilities, and other information.
  44.    Routers may act as directory mirrors (also called "caches"), to reduce
  45.    load on the directory authorities.  They announce this in their
  46.    descriptors.
  47.  
  48.    Each directory authority periodically generates and signs a compact
  49.    "network status" document that lists that authority's view of the current
  50.    descriptors and status for known routers, but which does not include the
  51.    descriptors themselves.
  52.  
  53.    Directory mirrors download, cache, and re-serve network-status documents
  54.    to clients.
  55.  
  56.    Clients, directory mirrors, and directory authorities all use
  57.    network-status documents to find out when their list of routers is
  58.    out-of-date.  If it is, they download any missing router descriptors.
  59.    Clients download missing descriptors from mirrors; mirrors and authorities
  60.    download from authorities.  Descriptors are downloaded by the hash of the
  61.    descriptor, not by the server's identity key: this prevents servers from
  62.    attacking clients by giving them descriptors nobody else uses.
  63.  
  64.    All directory information is uploaded and downloaded with HTTP.
  65.  
  66.    Coordination among directory authorities is done client-side: clients
  67.    compute a vote-like algorithm among the network-status documents they
  68.    have, and base their decisions on the result.
  69.  
  70. 1.1. What's different from 0.1.0.x?
  71.  
  72.    Clients used to download a signed concatenated set of router descriptors
  73.    (called a "directory") from directory mirrors, regardless of which
  74.    descriptors had changed.
  75.  
  76.    Between downloading directories, clients would download "network-status"
  77.    documents that would list which servers were supposed to running.
  78.  
  79.    Clients would always believe the most recently published network-status
  80.    document they were served.
  81.  
  82.    Routers used to upload fresh descriptors all the time, whether their keys
  83.    and other information had changed or not.
  84.  
  85. 2. Router operation
  86.  
  87.    The router descriptor format is unchanged from tor-spec.txt.
  88.  
  89.    ORs SHOULD generate a new router descriptor whenever any of the
  90.    following events have occurred:
  91.  
  92.       - A period of time (18 hrs by default) has passed since the last
  93.         time a descriptor was generated.
  94.  
  95.       - A descriptor field other than bandwidth or uptime has changed.
  96.  
  97.       - Bandwidth has changed by more than +/- 50% from the last time a
  98.         descriptor was generated, and at least a given interval of time
  99.         (20 mins by default) has passed since then.
  100.  
  101.       - Its uptime has been reset (by restarting).
  102.  
  103.    After generating a descriptor, ORs upload it to every directory
  104.    authority they know, by posting it to the URL
  105.  
  106.       http://<hostname:port>/tor/
  107.  
  108. 3. Network status format
  109.  
  110.    Directory authorities generate, sign, and compress network-status
  111.    documents.  Directory servers SHOULD generate a fresh network-status
  112.    document when the contents of such a document would be different from the
  113.    last one generated, and some time (at least one second, possibly longer)
  114.    has passed since the last one was generated.
  115.  
  116.    The network status document contains a preamble, a set of router status
  117.    entries, and a signature, in that order.
  118.  
  119.    We use the same meta-format as used for directories and router descriptors
  120.    in "tor-spec.txt".  Implementations MAY insert blank lines
  121.    for clarity between sections; these blank lines are ignored.
  122.    Implementations MUST NOT depend on blank lines in any particular location.
  123.  
  124.    As used here, "whitespace" is a sequence of 1 or more tab or space
  125.    characters.
  126.  
  127.    The preamble contains:
  128.  
  129.       "network-status-version" -- A document format version.  For this
  130.          specification, the version is "2".
  131.       "dir-source" -- The authority's hostname, current IP address, and
  132.          directory port, all separated by whitespace.
  133.       "fingerprint" -- A base16-encoded hash of the signing key's
  134.          fingerprint, with no additional spaces added.
  135.       "contact" -- An arbitrary string describing how to contact the
  136.          directory server's administrator.  Administrators should include at
  137.          least an email address and a PGP fingerprint.
  138.       "dir-signing-key" -- The directory server's public signing key.
  139.       "client-versions" -- A comma-separated list of recommended client
  140.         versions.
  141.       "server-versions" -- A comma-separated list of recommended server
  142.         versions.
  143.       "published" -- The publication time for this network-status object.
  144.       "dir-options" -- A set of flags, in any order, separated by whitespace:
  145.           "Names" if this directory authority performs name bindings.
  146.           "Versions" if this directory authority recommends software versions.
  147.  
  148.    The dir-options entry is optional.  The "-versions" entries are required if
  149.    the "Versions" flag is present.  The other entries are required and must
  150.    appear exactly once. The "network-status-version" entry must appear first;
  151.    the others may appear in any order.  Implementations MUST ignore
  152.    additional arguments to the items above, and MUST ignore unrecognized
  153.    flags.
  154.  
  155.    For each router, the router entry contains:  (This format is designed for
  156.    conciseness.)
  157.  
  158.       "r" -- followed by the following elements, in order, separated by
  159.           whitespace:
  160.           - The OR's nickname,
  161.           - A hash of its identity key, encoded in base64, with trailing =
  162.             signs removed.
  163.           - A hash of its most recent descriptor, encoded in base64, with
  164.             trailing = signs removed.  (The hash is calculated as for
  165.             computing the signature of a descriptor.)
  166.           - The publication time of its most recent descriptor, in the form
  167.             YYYY-MM-DD HH:MM:SS, in GMT.
  168.           - An IP address
  169.           - An OR port
  170.           - A directory port (or "0" for none")
  171.       "s" -- A series of whitespace-separated status flags, in any order:
  172.           "Authority" if the router is a directory authority.
  173.           "Exit" if the router is useful for building general-purpose exit
  174.              circuits.
  175.           "Fast" if the router is suitable for high-bandwidth circuits.
  176.           "Guard" if the router is suitable for use as an entry guard.
  177.              (Currently, this means 'fast' and 'stable'.)
  178.           "Named" if the router's identity-nickname mapping is canonical,
  179.              and this authority binds names.
  180.           "Stable" if the router is suitable for long-lived circuits.
  181.           "Running" if the router is currently usable.
  182.           "Valid" if the router has been 'validated'.
  183.           "V2Dir" if the router implements this protocol.
  184.  
  185.       The "r" entry for each router must appear first and is required.  The
  186.       's" entry is optional.  Unrecognized flags and extra elements on the
  187.       "r" line must be ignored.
  188.  
  189.    The signature section contains:
  190.  
  191.       "directory-signature". A signature of the rest of the document using
  192.       the directory authority's signing key.
  193.  
  194.    We compress the network status list with zlib before transmitting it.
  195.  
  196. 3.1. Establishing server status
  197.  
  198.    (This section describes how directory authorities choose which status
  199.    flags to apply to routers, as of Tor 0.1.1.18-rc. Later directory
  200.    authorities MAY do things differently, so long as clients keep working
  201.    well.  Clients MUST NOT depend on the exact behaviors in this section.)
  202.  
  203.    "Valid" -- a router is 'Valid' if it seems to have been running well for a
  204.    while, and is running a version of Tor not known to be broken, and the
  205.    directory authority has not blacklisted it as suspicious.
  206.  
  207.    "Named" -- Directory authority administrators may decide to support name
  208.    binding.  If they do, then they must maintain a file of
  209.    nickname-to-identity-key mappings, and try to keep this file consistent
  210.    with other directory authorities.  If they don't, they act as clients, and
  211.    report bindings made by other directory authorities (name X is bound to
  212.    identity Y if at least one binding directory lists it, and no directory
  213.    binds X to some other Y'.)  A router is called 'Named' if the router
  214.    believes the given name should be bound to the given key.
  215.  
  216.    "Running" -- A router is 'Running' if the authority managed to connect to
  217.    it successfully within the last 30 minutes.
  218.  
  219.    "Stable" -- A router is 'Stable' if its uptime is above median for known
  220.    running, valid routers, and it's running a version of Tor not known to
  221.    drop circuits stupidly.  (0.1.1.10-alpha throught 0.1.1.16-rc are stupid
  222.    this way.)
  223.  
  224.    "Fast" -- A router is 'Fast' if its bandwidth is in the top 7/8ths for
  225.    known running, valid routers.
  226.  
  227.    "Guard" -- A router is a possible 'Guard' if it is 'Stable' and its
  228.    bandwidth is above median for known running, valid routers.
  229.  
  230.    "Authority" -- A router is called an 'Authority' if the authority
  231.    generating the network-status document believes it is an authority.
  232.  
  233.    "V2Dir" -- A router supports the v2 directory protocol if it has an open
  234.    directory port, and it is running a version of the directory protocol that
  235.    supports the functionality clients need.  (Currently, this is
  236.    0.1.1.9-alpha or later.)
  237.  
  238.    Directory server administrators may label some servers or IPs as
  239.    blacklisted, and elect not to include them in their network-status lists.
  240.  
  241.    Thus, the network-status list includes all non-blacklisted,
  242.    non-expired, non-superseded descriptors for ORs that the directory has
  243.    observed at least once to be running.
  244.  
  245. 4. Directory server operation
  246.  
  247.    All directory authorities and directory mirrors ("directory servers")
  248.    implement this section, except as noted.
  249.  
  250. 4.1. Accepting uploads (authorities only)
  251.  
  252.    When a router posts a signed descriptor to a directory authority, the
  253.    authority first checks whether it is well-formed and correctly
  254.    self-signed.  If it is, the authority next verifies that the nickname
  255.    question is already assigned to a router with a different public key.
  256.    Finally, the authority MAY check that the router is not blacklisted
  257.    because of its key, IP, or another reason.
  258.  
  259.    If the descriptor passes these tests, and the authority does not already
  260.    have a descriptor for a router with this public key, it accepts the
  261.    descriptor and remembers it.
  262.  
  263.    If the authority _does_ have a descriptor with the same public key, the
  264.    newly uploaded descriptor is remembered if its publication time is more
  265.    recent than the most recent old descriptor for that router, and either:
  266.       - There are non-cosmetic differences between the old descriptor and the
  267.         new one.
  268.       - Enough time has passed between the descriptors' publication times.
  269.         (Currently, 12 hours.)
  270.  
  271.    Differences between router descriptors are "non-cosmetic" if they would be
  272.    sufficient to force an upload as described in section 2 above.
  273.  
  274.    Note that the "cosmetic difference" test only applies to uploaded
  275.    descriptors, not to descriptors that the authority downloads from other
  276.    authorities.
  277.  
  278. 4.2. Downloading network-status documents (authorities and caches)
  279.  
  280.    All directory servers (authorities and mirrors) try to keep a fresh
  281.    set of network-status documents from every authority.  To do so,
  282.    every 5 minutes, each authority asks every other authority for its
  283.    most recent network-status document.  Every 15 minutes, each mirror
  284.    picks a random authority and asks it for the most recent network-status
  285.    documents for all the authorities the authority knows about (including
  286.    the chosen authority itself).
  287.  
  288.    Directory servers and mirrors remember and serve the most recent
  289.    network-status document they have from each authority.  Other
  290.    network-status documents don't need to be stored.  If the most recent
  291.    network-status document is over 10 days old, it is discarded anyway.
  292.    Mirrors SHOULD store and serve network-status documents from authorities
  293.    they don't recognize, but SHOULD NOT use such documents for any other
  294.    purpose.  Mirrors SHOULD discard network-status documents older than 48
  295.    hours.
  296.  
  297. 4.3. Downloading and storing router descriptors (authorities and caches)
  298.  
  299.    Periodically (currently, every 10 seconds), directory servers check
  300.    whether there are any specific descriptors (as identified by descriptor
  301.    hash in a network-status document) that they do not have and that they
  302.    are not currently trying to download.
  303.  
  304.    If so, the directory server launches requests to the authorities for these
  305.    descriptors, such that each authority is only asked for descriptors listed
  306.    in its most recent network-status.  When more than one authority lists the
  307.    descriptor, we choose which to ask at random.
  308.  
  309.    If one of these downloads fails, we do not try to download that descriptor
  310.    from the authority that failed to serve it again unless we receive a newer
  311.    network-status from that authority that lists the same descriptor.
  312.  
  313.    Directory servers must potentially cache multiple descriptors for each
  314.    router. Servers must not discard any descriptor listed by any current
  315.    network-status document from any authority.  If there is enough space to
  316.    store additional descriptors, servers SHOULD try to hold those which
  317.    clients are likely download the most.  (Currently, this is judged based on
  318.    the interval for which each descriptor seemed newest.)
  319.  
  320.    Authorities SHOULD NOT download descriptors for routers that they would
  321.    immediately reject for reasons listed in 3.1.
  322.  
  323. 4.4. HTTP URLs
  324.  
  325.    "Fingerprints" in these URLs are base-16-encoded SHA1 hashes.
  326.  
  327.    The authoritative network-status published by a host should be available at:
  328.       http://<hostname>/tor/status/authority.z
  329.  
  330.    The network-status published by a host with fingerprint
  331.    <F> should be available at:
  332.       http://<hostname>/tor/status/fp/<F>.z
  333.  
  334.    The network-status documents published by hosts with fingerprints
  335.    <F1>,<F2>,<F3> should be available at:
  336.       http://<hostname>/tor/status/fp/<F1>+<F2>+<F3>.z
  337.  
  338.    The most recent network-status documents from all known authorities,
  339.    concatenated, should be available at:
  340.          http://<hostname>/tor/status/all.z
  341.  
  342.    The most recent descriptor for a server whose identity key has a
  343.    fingerprint of <F> should be available at:
  344.       http://<hostname>/tor/server/fp/<F>.z
  345.  
  346.    The most recent descriptors for servers with identity fingerprints
  347.    <F1>,<F2>,<F3> should be available at:
  348.       http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z
  349.  
  350.    (NOTE: Implementations SHOULD NOT download descriptors by identity key
  351.    fingerprint. This allows a corrupted server (in collusion with a cache) to
  352.    provide a unique descriptor to a client, and thereby partition that client
  353.    from the rest of the network.)
  354.  
  355.    The server descriptor with (descriptor) digest <D> (in hex) should be
  356.    available at:
  357.       http://<hostname>/tor/server/d/<D>.z
  358.  
  359.    The most recent descriptors with digests <D1>,<D2>,<D3> should be
  360.    available at:
  361.       http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z
  362.  
  363.    The most recent descriptor for this server should be at:
  364.       http://<hostname>/tor/server/authority.z
  365.     [Nothing in the Tor protocol uses this resource yet, but it is useful
  366.      for debugging purposes. Also, the official Tor implementations
  367.      (starting at 0.1.1.x) use this resource to test whether a server's
  368.      own DirPort is reachable.]
  369.  
  370.    A concatenated set of the most recent descriptors for all known servers
  371.    should be available at:
  372.       http://<hostname>/tor/server/all.z
  373.  
  374.    For debugging, directories SHOULD expose non-compressed objects at URLs like
  375.    the above, but without the final ".z".
  376.  
  377.    Clients MUST handle compressed concatenated information in two forms:
  378.      - A concatenated list of zlib-compressed objects.
  379.      - A zlib-compressed concatenated list of objects.
  380.    Directory servers MAY generate either format: the former requires less
  381.    CPU, but the latter requires less bandwidth.
  382.  
  383.    Clients SHOULD use upper case letters (A-F) when base16-encoding
  384.    fingerprints.  Servers MUST accept both upper and lower case fingerprints
  385.    in requests.
  386.  
  387. 5. Client operation: downloading information
  388.  
  389.    Every Tor that is not a directory server (that is, clients and ORs that do
  390.    not have a DirPort set) implements this section.
  391.  
  392. 5.1. Downloading network-status documents
  393.  
  394.    Each client maintains an ordered list of directory authorities.
  395.    Insofar as possible, clients SHOULD all use the same ordered list.
  396.  
  397.    For each network-status document a client has, it keeps track of its
  398.    publication time *and* the time when the client retrieved it.  Clients
  399.    consider a network-status document "live" if it was published within the
  400.    last 24 hours.
  401.  
  402.    Clients try to have a live network-status document hours from *every*
  403.    authority, and try to periodically get new network-status documents from
  404.    each authority in rotation as follows:
  405.  
  406.    If a client is missing a live network-status document for any
  407.    authority, it tries to fetch it from a directory cache.  On failure,
  408.    the client waits briefly, then tries that network-status document
  409.    again from another cache.  The client does not build circuits until it
  410.    has live network-status documents from more than half the authorities
  411.    it trusts, and it has descriptors for more than 1/4 of the routers
  412.    that it believes are running.
  413.  
  414.    If the most recently _retrieved_ network-status document is over 30
  415.    minutes old, the client attempts to download a network-status document.
  416.    When choosing which documents to download, clients treat their list of
  417.    directory authorities as a circular ring, and begin with the authority
  418.    appearing immediately after the authority for their most recently
  419.    retrieved network-status document.  If this attempt fails, the client
  420.    retries at other caches several times, before moving on to the next
  421.    network-status document in sequence.
  422.  
  423.    Clients discard all network-status documents over 24 hours old.
  424.  
  425.    If enough mirrors (currently 4) claim not to have a given network status,
  426.    we stop trying to download that authority's network-status, until we
  427.    download a new network-status that makes us believe that the authority in
  428.    question is running.  Clients should wait a little longer after each
  429.    failure.
  430.  
  431.    Clients SHOULD try to batch as many network-status requests as possible
  432.    into each HTTP GET.
  433.  
  434.    (Note: clients can and should pick caches based on the network-status
  435.    information they have: once they have first fetched network-status info
  436.    from an authority, they should not need to go to the authority directly
  437.    again.)
  438.  
  439. 5.2. Downloading router descriptors
  440.  
  441.    Clients try to have the best descriptor for each router.  A descriptor is
  442.    "best" if:
  443.       * It is the most recently published descriptor listed for that router
  444.         by at least two network-status documents.
  445.         OR,
  446.       * No descriptor for that router is listed by two or more
  447.         network-status documents, and it is the most recently published
  448.         descriptor listed by any network-status document.
  449.  
  450.    Periodically (currently every 10 seconds) clients check whether there are
  451.    any "downloadable" descriptors.  A descriptor is downloadable if:
  452.       - It is the "best" descriptor for some router.
  453.       - The descriptor was published at least 10 minutes in the past.
  454.         (This prevents clients from trying to fetch descriptors that the
  455.         mirrors have probably not yet retrieved and cached.)
  456.       - The client does not currently have it.
  457.       - The client is not currently trying to download it.
  458.       - The client would not discard it immediately upon receiving it.
  459.       - The client thinks it is running and valid (see 6.1 below).
  460.  
  461.    If at least 16 known routers have downloadable descriptors, or if
  462.    enough time (currently 10 minutes) has passed since the last time the
  463.    client tried to download descriptors, it launches requests for all
  464.    downloadable descriptors, as described in 5.3 below.
  465.  
  466.    When a descriptor download fails, the client notes it, and does not
  467.    consider the descriptor downloadable again until a certain amount of time
  468.    has passed. (Currently 0 seconds for the first failure, 60 seconds for the
  469.    second, 5 minutes for the third, 10 minutes for the fourth, and 1 day
  470.    thereafter.)  Periodically (currently once an hour) clients reset the
  471.    failure count.
  472.  
  473.    No descriptors are downloaded until the client has downloaded more than
  474.    half of the network-status documents.
  475.  
  476. 5.3. Managing downloads
  477.  
  478.    When a client has no live network-status documents, it downloads
  479.    network-status documents from a randomly chosen authority.  In all other
  480.    cases, the client downloads from mirrors randomly chosen from among those
  481.    believed to be V2 directory servers.  (This information comes from the
  482.    network-status documents; see 6 below.)
  483.  
  484.    When downloading multiple router descriptors, the client chooses multiple
  485.    mirrors so that:
  486.      - At least 3 different mirrors are used, except when this would result
  487.        in more than one request for under 4 descriptors.
  488.      - No more than 128 descriptors are requested from a single mirror.
  489.      - Otherwise, as few mirrors as possible are used.
  490.    After choosing mirrors, the client divides the descriptors among them
  491.    randomly.
  492.  
  493.    After receiving any response client MUST discard any network-status
  494.    documents and descriptors that it did not request.
  495.  
  496. 6. Using directory information
  497.  
  498.    Everyone besides directory authorities uses the approaches in this section
  499.    to decide which servers to use and what their keys are likely to be.
  500.    (Directory authorities just believe their own opinions, as in 3.1 above.)
  501.  
  502. 6.1. Choosing routers for circuits.
  503.  
  504.    Tor implementations only pay attention to "live" network-status documents.
  505.    A network status is "live" if it is the most recently downloaded network
  506.    status document for a given directory server, and the server is a
  507.    directory server trusted by the client, and the network-status document is
  508.    no more than 1 day old.
  509.  
  510.    For time-sensitive information, Tor implementations focus on "recent"
  511.    network-status documents.  A network status is "recent" if it is live, and
  512.    if it was published in the last 60 minutes.  If there are fewer
  513.    than 3 such documents, the most recently published 3 are "recent."  If
  514.    there are fewer than 3 in all, all are "recent.")
  515.  
  516.    Circuits SHOULD NOT be built until the client has enough directory
  517.    information: network-statuses (or failed attempts to download
  518.    network-statuses) for all authorities, network-statuses for at more than
  519.    half of the authorites, and descriptors for at least 1/4 of the servers
  520.    believed to be running.
  521.  
  522.    A server is "listed" if it is included by more than half of the live
  523.    network status documents.  Clients SHOULD NOT use unlisted servers.
  524.  
  525.    Clients believe the flags "Valid", "Exit", "Fast", "Guard", "Stable", and
  526.    "V2Dir" about a given router when they are asserted by more than half of
  527.    the live network-status documents.  Clients believe the flag "Running" if
  528.    it is listed by more than half of the recent network-status documents.
  529.  
  530.    These flags are used as follows:
  531.  
  532.      - Clients SHOULD NOT use non-'Valid' or non-'Running' routers unless
  533.        requested to do so.
  534.  
  535.      - Clients SHOULD NOT use non-'Fast' routers for any purpose other than
  536.        very-low-bandwidth circuits (such as introduction circuits).
  537.  
  538.      - Clients SHOULD NOT use non-'Stable' routers for circuits that are
  539.        likely to need to be open for a very long time (such as those used for
  540.        IRC or SSH connections).
  541.  
  542.      - Clients SHOULD NOT choose non-'Guard' nodes when picking entry guard
  543.        nodes.
  544.  
  545.      - Clients SHOULD NOT download directory information from non-'V2Dir'
  546.        caches.
  547.  
  548. 6.1. Managing naming
  549.  
  550.    In order to provide human-memorable names for individual server
  551.    identities, some directory servers bind names to IDs.  Clients handle
  552.    names in two ways:
  553.  
  554.    When a client encounters a name it has not mapped before:
  555.  
  556.       If all the live "Naming" network-status documents the client has
  557.       claim that the name binds to some identity ID, and the client has at
  558.       least three live network-status documents, the client maps the name to
  559.       ID.
  560.  
  561.    If a client encounters a name it has mapped before:
  562.  
  563.       It uses the last-mapped identity value, unless all of the "Naming"
  564.       network status documents that list the name bind it to some other
  565.       identity.
  566.  
  567.    When a user tries to refer to a router with a name that does not have a
  568.    mapping under the above rules, the implementation SHOULD warn the user.
  569.    After giving the warning, the implementation MAY use a router that at
  570.    least one Naming authority maps the name to, so long as no other naming
  571.    authority maps that name to a different router.
  572.  
  573.    (XXXX The last-bound thing above isn't implemented)
  574.  
  575. 6.2. Software versions
  576.  
  577.    An implementation of Tor SHOULD warn when it has fetched (or has
  578.    attempted to fetch and failed four consecutive times) a network-status
  579.    for each authority, and it is running a software version
  580.    not listed on more than half of the live "Versioning" network-status
  581.    documents.
  582.  
  583. 6.3. Warning about a router's status.
  584.  
  585.    If a router tries to publish its descriptor to a Naming authority
  586.    that has its nickname mapped to another key, the router SHOULD
  587.    warn the operator that it is either using the wrong key or is using
  588.    an already claimed nickname.
  589.  
  590.    If a router has fetched (or attempted to fetch and failed four
  591.    consecutive times) a network-status for every authority, and at
  592.    least one of the authorities is "Naming", and no live "Naming"
  593.    authorities publish a binding for the router's nickname, the
  594.    router SHOULD remind the operator that the chosen nickname is not
  595.    bound to this key at the authorities, and suggest contacting the
  596.    authority operators.
  597.  
  598.    ...
  599.  
  600.